解決 WSL 2 Docker 檔案權限問題

TLDR

核心問題：WSL 2 中 Docker 容器以 root 權限建立檔案，導致本機使用者（如 VS Code）因權限不足無法編輯。
不推薦做法：將 WSL 預設使用者改為 root，此舉會導致系統失去權限隔離，風險極高。
推薦做法 (一)：使用 VS Code 的 Dev Containers 功能，透過容器化開發環境解決權限與環境一致性問題。
推薦做法 (二)：若需與現有 docker-compose 整合，可建立一個專屬的 vscode-editor 容器並掛載工作目錄，透過 remoteUser: root 解決編輯權限。
關鍵建議：使用 docker-outside-of-docker 時，建議優先使用 Named Volume 以避開 Bind Mount 在跨作業系統時的路徑解析與權限地獄。

權限地獄的成因

什麼情況下會遇到這個問題：當你在 WSL 2 環境中使用 Docker Compose 啟動服務，且該服務以 root 身分在掛載目錄（Bind Mount）中建立檔案時。

由於 Docker 容器內部的 root 與 WSL 外部的一般使用者（如 wing）在 Linux 權限系統中被視為不同實體，導致外部編輯器（如 VS Code）嘗試讀寫這些檔案時會觸發 Permission Denied 錯誤。

暴力解法的風險

什麼情況下會遇到這個問題：當開發者為了快速解決權限阻礙，選擇修改 /etc/wsl.conf 將預設使用者改為 root。

WARNING

這是一個極度不安全的作法。將預設使用者改為 root 會讓你在 WSL 內的所有操作都具有最高權限，一旦誤執行惡意腳本或操作失誤（例如 rm -rf /），後果不堪設想。請勿在生產環境或重要的工作環境中模仿。

Dev Containers：優雅的開發環境

什麼情況下會遇到這個問題：當你希望在保持系統安全的前提下，解決跨環境的檔案存取與開發工具配置問題。

Dev Containers 允許將開發環境打包在容器中，並自動處理 UID 對應。針對 Docker Compose 產生的 root 檔案，可透過設定 remoteUser: "root" 來確保編輯器擁有足夠權限。

實戰設定步驟

初始化：在專案目錄按下 F1，選擇 Dev Containers: Add Dev Container Configuration Files...。
選擇定義：選擇適合的環境（如 Ubuntu），並務必勾選 Docker (outside of Docker) 功能。

設定 devcontainer.json：若使用 Bind Mount，必須在設定檔中啟用 remoteUser：

json

{
    "image": "mcr.microsoft.com/devcontainers/base:noble",
    "features": {
        "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
            "installDockerBuildx": true,
            "installDockerComposeSwitch": true,
            "version": "latest",
            "dockerDashComposeVersion": "v2"
        }
    },
    "remoteUser": "root"
}

重新載入：按下 F1 選擇 Dev Containers: Reopen in Container 即可進入環境。

TIP

devcontainer.json 修改後必須執行 Rebuild 才會生效。若指令面板找不到重建選項，可執行 Developer: Reload Window 重新連線。

整合至 Docker Compose 的替代方案

什麼情況下會遇到這個問題：當你不希望為每個專案額外維護 .devcontainer 資料夾，或希望開發工具容器與正式服務共用網路時。

你可以在 compose.yml (或 compose.override.yml) 中加入一個專用的編輯器容器：

yaml

services:
  vscode-editor:
    image: mcr.microsoft.com/devcontainers/base:ubuntu-24.04
    container_name: vscode-editor
    command: sleep infinity
    user: root
    volumes:
      - ./:/workspace
    working_dir: /workspace

啟動後，透過 Dev Containers: Attach to Running Container... 指令連線至 vscode-editor，並將該容器的設定檔中 remoteUser 設為 root，即可在容器內無縫編輯所有檔案。

TIP

若不想污染正式的 compose.yml，建議將上述設定移至 compose.override.yml，Docker Compose 會在啟動時自動合併設定。

異動歷程

2026-01-19 初版文件建立。
2026-01-22 補充將 Dev Container 整合進 Docker Compose 的另一種做法。
2026-02-04 補充關於使用 compose.override.yml 的建議。

筆記目錄

解決 WSL 2 Docker 檔案權限問題 ​

TLDR ​

權限地獄的成因 ​

暴力解法的風險 ​

Dev Containers：優雅的開發環境 ​

實戰設定步驟 ​

整合至 Docker Compose 的替代方案 ​

異動歷程 ​